Playing Notes with the Note Allocator

Playing a few notes with the note allocator component is simple and straightforward. To play notes that have a piano sound, for example, you need to open up the note allocator component, allocate a note channel with a request for piano, and play. When you've finished playing notes, you dispose of the note channel and close the note allocator component. The code to accomplish this is shown in Listing 2 . Before working through the code, you need to look at some important related data structures.

Note-related Data Structures

A note channel is analogous to a sound channel in that you allocate it, issue commands to it to produce sound, and close it when you're done. To specify details about the note channel, you use a data structure called a NoteRequest (see Listing 1 ).

Listing 1 Note-related data structures



 
struct NoteRequest {

    NoteRequestInfo   info;      // * in post-QuickTime 2.0 only

    ToneDescription   tone;

};



struct NoteRequestInfo {

    UInt8      flags;

    UInt8      reserved;

    short      polyphony;

    Fixed      typicalPolyphony;

};



struct ToneDescription {

    OSType   synthesizerType;

    Str31      synthesizerName;

    Str31      instrumentName;

    long      instrumentNumber;

    long      gmNumber;

};

The next two fields specify the probable polyphony that the note channel will be used for. Polyphony means, literally, many sounds. A polyphony of 5 means that five notes can be playing simultaneously. The polyphony field enables QTMA to make sure that the allocated note channel can play all the notes you need. The typical Polyphony field is a fixed-point number that should be set to the average number of voices the note channel will play; it may be whole or fractional. Some music components use this field to adjust the mixing level for a good volume. If in doubt, set the typical Polyphony field to 0X00010000.

The ToneDescription structure is used throughout QTMA to specify a musical instrument sound in a device-independent fashion. This structure's synthesizerType and synthesizerName fields can request a particular synthesizer to play notes on. Usually, they're set to 0, meaning "choose the best General MIDI synthesizer." The gmNumber field indicates the General MIDI (GM) instrument or drum kit sound, which may be any of 135 such sounds supported by many synthesizer manufacturers. (All these sounds are available on a General MIDI Sound Module.) The GM instruments are numbered 1 through 128, and the seven drum kits are numbered 16385 and higher. For synthesizers that accept sounds outside the GM library, you can use the instrumentName and instrumentNumber fields to specify some other sound.